# Purpose: Defines Pydantic models for MCP web automation tool parameters and results.
# Changes:
# - No major functional changes from the previous correct version.
# - Added comments clarifying usage.

from pydantic import BaseModel, Field
from typing import Optional, List, Dict, Any

class InteractableElement(BaseModel):
    """Represents an interactable element identified during observation."""
    agent_id: str = Field(..., description="Temporary, observation-specific ID assigned by the agent/skill (e.g., 'el1'). Used to refer to this element in subsequent actions.")
    tag_name: str = Field(..., description="HTML tag name (e.g., 'a', 'button', 'input').")
    text: Optional[str] = Field(None, description="Visible text content of the element (potentially truncated).")
    attributes: Dict[str, Any] = Field(default_factory=dict, description="Key HTML attributes (e.g., 'href', 'aria-label', 'placeholder'). Values might be truncated.")

class ObservePageParams(BaseModel):
    """Parameters for the 'observe_page' tool."""
    focus_selector: Optional[str] = Field(None, description="Optional CSS selector to focus text extraction.")

class PageObservation(BaseModel):
    """Result returned by the 'observe_page' tool."""
    url: Optional[str] = Field(None, description="Current URL of the page.")
    title: Optional[str] = Field(None, description="Title of the page.")
    focused_text: Optional[str] = Field(None, description="Extracted text content (potentially truncated).")
    interactable_elements: List[InteractableElement] = Field(default_factory=list, description="List of identified interactable elements.")
    observation_summary: Optional[str] = Field(None, description="Optional brief summary of the page state.")
    error_message: Optional[str] = Field(None, description="Error message if observation failed partially or completely.")

class NavigateParams(BaseModel):
    """Parameters for the 'navigate' tool."""
    url: str = Field(..., description="Target URL (e.g., 'https://example.com').")

class ClickElementParams(BaseModel):
    """Parameters for the 'click_element' tool."""
    element_id: str = Field(..., description="The 'agent_id' of the element to click (from 'observe_page').")

class TypeTextParams(BaseModel):
    """Parameters for the 'type_text' tool."""
    element_id: str = Field(..., description="The 'agent_id' of the input element (from 'observe_page').")
    text_to_type: str = Field(..., description="The text to type.")
    clear_first: bool = Field(True, description="Whether to clear the field before typing.")

class GetTextContentParams(BaseModel):
     """Parameters for the 'get_text_content' tool."""
     selector: Optional[str] = Field(None, description="Optional CSS selector. If None, gets text from body.")